This PR adds an additional method to ForwardsCalls to allow for easy fluent calls to decorated objects. This pattern is used in the Relation class as well as in the DecoratesQueryBuilder trait that will be introduced in Laravel 9. Under the hood, this essentially performs:

public function __call($method, $parameters)
{
  $result = $this->forwardCallTo($this->decorated, $method, $parameters);

  // If the underlying call was fluent, make this call fluent as well
  if ($result === $this->decorated) {
    return $this;
  }

  return $result;
}

This is a nice solution, because we continue to receive our proxy object until we make a call that isn't fluent on the underlying decorated object.

There are a handful of places that could be updated to use this new method. Because these are mild breaking changes, I'll introduce them in 9.x PR should this PR get merged. These are:

• Illuminate\Events\NullDispatcher
• Illuminate\Http\Resources\DelegatesToResource
• Illuminate\Mail\Message
• Illuminate\Pagination\AbstractPaginator and AbstractCursorPaginator

In each of these cases, I believe the expected behavior of any delegated fluent call would be to receive the proxy object, whereas right now you would receive the underlying object.

For example, in the case of Illuminate\Mail\Message:

// Works because you happen to call from() first
$message->from('foo@bar.com')->addPart('hello', 'text/plain');

// Fails because you call from() second, and `addPart()` returned the underlying Swift_Message
$message->addPart('hello', 'text/plain')->from('foo@bar.com');